<?php
/***************************************************************************
                                  Class4.php
                              -------------------
  
        A PHP5 class used as a reference to test methods parsing. 

 **************************************************************************/
 
/**
 * Class to test methods parsing.
 *
 * This class presents a lot of method declaration statements to test
 * most of parsing possibilities.
 */
class Class4 {

/**
 * Constructor with PHP5 class syntax.
 *
 * This method prints a message when an instance is created.
 */
function __construct() {

  echo "A new instance has been created.";
}

/**
 * A method example with 3 parameters.
 *
 * The three parameters have different declaration patterns.
 *
 * @param (string) $p1 the first parameter
 * @param (int) $p2 the second parameter
 * @param (bool) $p3 the third parameter
 * @return (bool) true is success, false either
 */
public static function three_param($p1, int $p2, $p3 = true) {

  // Print the 3 parameters
  echo $p1 . "\n";
  echo $p2 . "\n";
  echo $p3 . "\n";

  return true;
}

/**
 * A method with parameters passed by reference.
 *
 * @warning  unstable
 * @param (string) $p1 the 1st parameter
 * @param (bool) $p2 the 2nd parameter which
 *                   has a two-line comment
 * @return (string) the function result
 */
protected function pass_byref(& $p1, bool &$p2) {

  // No comment!
  return $p1;
}

/**
 * A method with no parameter.
 *
 * @experimental
 * @return (void)
 */
final private function noparam() {

  // No comment!
  print get_class_name($this);
}

/**
 * A method with a lot of description and @info items.
 *
 * Long description of func3 method is spread on two
 * paragraphs (skip next line).
 *
 * This is the other paragraph.
 *
 * Smart conversions of code source comment:
 *
 * 1) blank lines are converted to <br /> lines
 *
 * 2) an unordered list is a sequence of lines starting all with same -+* bullet,
 * indented on same column at least 2 spaces from margin star, so
 *
 *     - list item 1
 *       on two lines
 *     - second item
 *     - another list item
 *            + sublist it1
 *            + sublist it2
 *                 * subsub A
 *                 * subsub B
 *                 * subsub C
 *     - another ?
 *       again!
 *
 * is translate into an HTML unordered list <ul></ul> (max 8 items by list, 
 * nested up to 4 levels)
 *
 * 3) a list of array key alternatives is a sequence of lines starting with  keys 
 * in '' or [] or digits, indented on same column at least 2 spaces from margin star
 * and spread on 16 items maximum
 *
 *    'alt1' => first alternative
 *              array values can be multilined
 *    'alt2' => other
 *    'alt3' => last
 *
 * digit keys example:
 *
 *     0 => arrays can be nested
 *     1 => like this 
 *
 * simplified print_r (also var_export and var_dump) style example:
 *
 *     [print_color] => 
 *             // keys in this array are the method names
 *             [param] => 
 *                 [structfile] => 
 *                          [type] => 
 *                          [description] => 
 *                  [output] => 
 *                          [default] => 
 *                          [type] => 
 *                          [description] => 
 *             [return] => 
 *                  [0] => 
 *                          [type] => 
 *                          [description] => 
 *
 * is translated in an HTML <pre></pre> indentation
 *
 * @warning  unstable
 * @private  
 * @forfun  a three-line non-sense info,
 *          to show that you can create
 *          your own @info kewords
 * @param (int) $p1 the first parameter
 * @param (mixed) $p2 the title of text (string)
 *                    or false (bool) to get all
 * @param (string) $p3 the third parameter
 *                  is commented onto
 *                  several lines
 *                  - list item A
 *                  - list item B
 * @param (array) $p4 the address structured list:
 *                    'name' => a name
 *                    'address' => an address
 *                    'city' => a city name
 * @return (void) if echo flag $p1 is true
 *                a line of comment to test parsing
 *         (string) the printable solution if echo flag is false (default)
 *         (array) the raw solution
 *                 [structfile] => 
 *                          [type] => 
 *                          [description] => 
 *                 [output] => 
 *                          [default] => 
 *                          [type] => 
 *                          [description] => 
 */
final function lot_of_desc($p1, $p2="a string", string $p3 = "another string", $p4 = array()) {

  if ($p1) {
    return;
  } else {
    return "whatever";
  }
}

/**
 * Very simple method with PHP4 style.
 *
 * This method is declared like it would be in a PHP4 class.
 *
 * @public
 */
function hello() {

  echo "Hello world!";
}
}
?>
